6.04. Руководство по техническому обслуживанию по ГОСТ 19.508-79
Руководство по техническому обслуживанию
1. Введение: ГОСТ 19.508-79 — краткий обзор
ГОСТ 19.508-79 — советский государственный стандарт из состава Единой системы программной документации (ЕСПД), принятый 11 декабря 1979 г., введён в действие с 1 января 1981 г. Он определяет требования к содержанию и оформлению документа «Руководство по техническому обслуживанию» (РТО).
🎯 Назначение стандарта
Стандарт регламентирует структуру и содержание документа, предназначенного для специалистов по техническому обслуживанию (инженеров, операторов, администраторов), эксплуатирующих тестовые и диагностические программы, используемые при обслуживании технических средств (аппаратуры, оборудования, вычислительных комплексов).
⚠ Обратите внимание: хотя ГОСТ 19.508-79 формально применяется к диагностике и тестированию оборудования, его принципы применимы и к современным программным системам, особенно в контексте:
- мониторинга и самодиагностики (health checks),
- процедур восстановления (recovery procedures),
- профилактического обслуживания (preventive maintenance),
- инструментов DevOps и SRE (например, инвентаризация, проверка целостности, регрессионные тесты инфраструктуры).
📦 Область применения
Стандарт не распространяется на:
- пользовательские инструкции (это — ГОСТ 19.504),
- программные документы общего назначения (ГОСТ 19.501–19.509),
- проектную и конструкторскую документацию.
Он применим к:
- тестовым программам (self-test, burn-in, soak tests),
- диагностике неисправностей оборудования (memory, disk, CPU, network),
- средствам автоматизированной проверки состояния систем.
📐 Общая структура документа по ГОСТ
| Раздел | Обязательность | Комментарий |
|---|---|---|
| Титульный лист | ✅ Обязательно | По ГОСТ 19.105-78 |
| Аннотация | ✅ Обязательно | Краткое описание назначения и области применения РТО |
| Содержание | ✅ Обязательно | Дерево разделов и подразделов с номерами страниц |
| Введение | ✅ Обязательно | Назначение РТО, перечень сопутствующих эксплуатационных документов |
| Общие указания | ✅ Обязательно | Порядок, организация и особенности проведения ТО |
| Требования к техническим средствам | ✅ Обязательно | Минимальная конфигурация оборудования для запуска программы |
| Описание функций | ✅ Обязательно | Подробное описание функциональности диагностической программы |
| Дополнительные разделы | 🟡 Опционально | Например: «Меры безопасности», «Аварийные ситуации», «Журналирование», «Примеры использования» |
📌 Примечание:
- Все разделы оформляются по ГОСТ 19.105-78 (требования к построению, изложению, оформлению и содержанию программных документов).
- В современной практике вместо «технических средств» подразумевается инфраструктурная среда: серверы, ОС, сетевые интерфейсы, виртуальные/контейнеризованные окружения.
- Стандарт не требует строго литературного качества — важна точность, однозначность и полнота информации.
2. Пошаговое руководство по составлению РТО
Ниже приведено пошаговое руководство по написанию РТО. Каждый шаг включает:
- что делать,
- почему это важно,
- как оформлять (с учётом современной практики технического письма).
Шаг 1. Подготовка — сбор информации
Перед началом работы необходимо:
- получить спецификацию диагностируемой системы (аппаратной или программной),
- выделить функции самодиагностики или тестирования,
- определить целевую аудиторию (например: инженер 2-й категории, SRE, техподдержка),
- уточнить сценарии использования: штатная проверка, восстановление после сбоя, предварительная приёмка.
Шаг 2. Составьте информационную часть
Обязательные элементы:
- Титульный лист:
Включает наименование документа, код по ГОСТ (19.508), идентификатор системы/версии, дату, организацию-разработчика. - Аннотация (резюме):
Объём — 3–5 предложений. Ответьте на вопросы:- Что это за документ?
- Для какой системы/программы?
- Кто читатель?
- Какие операции охватывает (диагностика, калибровка, сброс)?
- Содержание:
Генерируется автоматически при финальной сборке (например, в Docusaurus, Confluence, или черезpandoc --toc).
Шаг 3. Раздел «Введение»
Что включить:
- Назначение РТО: «Настоящий документ предназначен для специалистов по техническому обслуживанию и содержит инструкции по диагностике и восстановлению работоспособности системы X».
- Перечень сопутствующих документов (обязательно!):
- Руководство оператора (ГОСТ 19.504),
- Описание применения (ГОСТ 19.502),
- Программа и методика испытаний (ГОСТ 19.301),
- Техническое задание (ГОСТ 19.201),
- Руководство администратора (если есть),
- API Reference, OpenAPI/Swagger-спецификации (в современной практике).
Формат рекомендуется табличный:
| Наименование документа | Обозначение | Примечание |
|---|---|---|
| Руководство оператора | РО-X-v2.1 | Версия 2.1, 2025 г. |
| Описание применения | ОП-X-2025 | Используется при интеграции в ELK |
Шаг 4. Раздел «Общие указания»
Ключевые подпункты:
- Общая последовательность действий (например: «1. Подготовка → 2. Запуск диагностической процедуры → 3. Анализ результатов → 4. Принятие решений»).
- Периодичность проведения: штатная (ежедневно), после сбоя, перед обновлением.
- Организационные требования:
- Требуемая квалификация персонала (например: «инженер по эксплуатации, аттестованный по программе Х»),
- Необходимые разрешения (доступ к консоли, права
sudo, MFA).
- Особые условия: температура, ЭМ-помехи, отключение от сети и т.п. (для hardware) или изоляция окружения (для ПО — например, запуск в
maintenance mode).
Шаг 5. Раздел «Требования к техническим средствам»
Фокус — на минимальные требования.
В современном контексте это требования к среде выполнения. Пример структуры:
| Категория | Минимальные требования | Рекомендуемые |
|---|---|---|
| ОС | Ubuntu 22.04 LTS, ядро ≥ 5.15 | Ubuntu 24.04 LTS |
| Процессор | 2 ядра, x86_64 | 4+ ядер, AES-NI |
| Память | 2 ГБ ОЗУ | 8 ГБ ОЗУ |
| Дисковое пространство | 500 МБ свободно | SSD, 5 ГБ |
| Сетевые интерфейсы | IPv4, localhost | IPv6, TLS 1.3 |
| Зависимости | Python 3.10+, psutil, requests | Python 3.12, виртуальное окружение |
| Права доступа | diag-user в группе adm | RBAC: role:diagnostic |
✅ Правило: указывайте версии строго (не «Python 3.x», а «Python ≥ 3.10, < 3.13»). При изменении требований — фиксируйте мажорную версию РТО.
Шаг 6. Раздел «Описание функций»
Самый объёмный и технически насыщенный раздел. Структура по ГОСТ:
-
Максимальный состав технических средств, проверяемых программой
→ В современном понимании: поддерживаемые компоненты системы (например: БД PostgreSQL, брокер RabbitMQ, frontend-контейнеры).
Лучше оформить в виде таблицы совместимости (см. ниже). -
Описание совместного функционирования технических средств и программы
→ Требуется:- описание workflow (например: «программа инициирует HTTP-запрос к
/health, ожидает 200 OK в течение 5 с»), - метод обработки ошибок (логика обработки
timeout,5xx,connection refused), - действия при выявлении неисправности (например: «при коде 0x7E — перезапуск сервиса
auth-service»).
- описание workflow (например: «программа инициирует HTTP-запрос к
-
Организация входных и выходных данных
→ Укажите:- формат входных параметров (CLI-аргументы, env-vars, конфиг-файл),
- структуру выходных данных (JSON schema, CLI exit codes, syslog-сообщения),
- коды возврата:
0 — OK (все проверки пройдены)
1 — предупреждение (рекомендуется вмешательство)
2 — критическая ошибка (система неработоспособна)
3 — ошибка среды (не хватает прав/ресурсов)
-
Описание взаимодействия устройств с программой
→ Для software-систем: это интерфейсы и сценарии взаимодействия.
Пример:- «Программа
diag-netопрашивает все активные сетевые интерфейсы черезnetlinkсокет», - «При обнаружении
packet loss > 5%— отправляет alert в Prometheus через Pushgateway», - «Результаты сохраняются в
/var/log/diag/net-<timestamp>.json».
- «Программа
Шаг 7. Дополнительные рекомендуемые разделы (современные практики)
Хотя ГОСТ их не требует, они повышают ценность документа:
- Меры безопасности
(например: «Программа не должна запускаться от root. ИспользуйтеsystemdсUser=diagиNoNewPrivileges=yes»). - Журналирование и мониторинг
(формат логов, интеграция с Grafana/Prometheus, retention policy). - Примеры запуска
(CLI-команды с комментариями, скриншоты терминала — но в текстовом формате!). - Устранение типовых неисправностей
(FAQ-style: «ОшибкаERR_CONN_REFUSED→ проверитьsystemctl status netd»).
3. Типичные ошибки и как их избежать
Особенно актуально при обучении начинающих технических писателей.
| Ошибка | Почему это плохо | Как избежать |
|---|---|---|
| Размытые формулировки «программа работает на компьютере» | Не позволяет воспроизвести среду | Указывайте точные версии, архитектуру, зависимости. Используйте термины: x86_64, arm64/v8, glibc 2.35+. |
| Отсутствие кодов возврата | Инженер не знает, что делать при exit code = 255 | Включайте таблицу exit codes. Согласуйте с разработчиками. |
| Нет ссылок на другие документы | Читатель «застревает» — не знает, где искать доп. информацию | В «Введении» дайте полный перечень с обозначениями и версиями. |
| Смешение уровней абстракции — описание «как работает алгоритм CRC-32» в РТО | РТО — не справочник разработчика | Описывайте поведение, не реализацию. «Программа проверяет контрольную сумму образа диска» — достаточно. |
| Нет примеров | Теория без практики → ошибки при выполнении | Добавляйте 1–2 рабочих примера с пояснением каждой опции. |
| Игнорирование безопасности | Запуск с sudo «для удобства» → уязвимости | Выделяйте блоки «Security Note»: ⚠ Не используйте --force в production. |
| Однократное написание, без актуализации | Документ устаревает быстрее, чем ПО | Пропишите в титуле: «Последнее обновление: 2025-11-11. Актуально для версии X v3.2.1». Завяжите на CI: если изменился CLI — запретить мердж без обновления РТО. |
🔁 Правило обратной связи: каждая процедура в РТО должна быть проверена на стенде человеком, не участвовавшим в разработке.
4. Пример РТО для вымышленной системы
Система XenonCache v2.1
Распределённая система кэширования данных с встроенной самодиагностикой
📌 Пояснение: XenonCache — виртуальная система. Для целей демонстрации:
- это stateless кэш-сервер на базе in-memory хранилища,
- поддерживает кластеризацию, репликацию, автоматическое восстановление,
- содержит встроенную утилиту диагностики
xenon-diag(CLI + HTTP API),- предназначена для эксплуатации инженерами SRE-группы.
Документ оформляется строго по структуре ГОСТ 19.508-79, с дополнениями современных практик (без нарушения требований стандарта).
📄 Руководство по техническому обслуживанию
Система XenonCache, версия 2.1
Документ: РТО-XC-2.1
Дата составления: 11.11.2025
Разработчик: ООО «НейтронЛабс»
Аннотация
Настоящий документ содержит инструкции по техническому обслуживанию распределённой кэш-системы XenonCache версии 2.1 с использованием встроенной диагностической программы xenon-diag. Предназначен для инженеров по эксплуатации и SRE. Описывает порядок запуска, интерпретацию результатов, обработку ошибок и действия при выявлении неисправностей. Обеспечивает соответствие требованиям надёжности и восстанавливаемости в условиях 24/7 эксплуатации.
Содержание
- Введение
- Общие указания
- Требования к техническим средствам
- Описание функций
4.1. Максимальный состав проверяемых технических средств
4.2. Совместное функционирование и обработка ошибок
4.3. Организация входных и выходных данных
4.4. Взаимодействие устройств с программой и вывод результатов
1. Введение
Настоящее Руководство по техническому обслуживанию (РТО) предназначено для специалистов, ответственных за эксплуатацию и обслуживание распределённой кэш-системы XenonCache v2.1. Оно описывает процедуры диагностики и контроля работоспособности с помощью программы xenon-diag, входящей в поставку XenonCache.
Для полного выполнения задач технического обслуживания дополнительно используются следующие документы:
| Наименование документа | Обозначение | Примечание |
|---|---|---|
| Руководство оператора | РО-XC-2.1 | Содержит описание интерфейсов управления и мониторинга |
| Описание применения | ОП-XC-2.1 | Условия интеграции, сценарии использования |
| Программа и методика испытаний | ПМИ-XC-2.1 | Испытания при приёмке |
| Спецификация HTTP API | SPEC-XC-HTTP-v2 | OpenAPI 3.1, доступна по /openapi.json |
| Инструкция по развёртыванию | DEPLOY-XC-K8S | Для окружения Kubernetes |
2. Общие указания
Техническое обслуживание XenonCache выполняется с периодичностью:
- Ежедневно: лёгкая диагностика (
xenon-diag --mode quick); - Еженедельно: полная диагностика (
xenon-diag --mode full --replicas all); - По требованию: после сбоя, перед обновлением, при расширении кластера.
Порядок проведения:
-
Подготовка
- Убедиться, что все узлы в состоянии
Ready(kubectl get nodes). - Перевести кластер в режим обслуживания (через
PUT /api/v1/maintenance?enable=true). - Проверить наличие свободного дискового пространства (
df -h /var/lib/xenon≥ 20%).
- Убедиться, что все узлы в состоянии
-
Запуск диагностики
- Выполнить
xenon-diagс нужным режимом (см. п. 4.3). - Сохранить выходные данные в архив (
/var/log/xenon/diag/YYYYMMDD_HHMM.tar.gz).
- Выполнить
-
Анализ результатов
- Проверить код возврата (см. табл. 4.3.1).
- При коде ≥ 1 — свериться с таблицей ошибок (прил. A).
- При выявлении проблем — выполнить рекомендации из раздела 4.2.
-
Завершение
- Отключить режим обслуживания (
PUT /api/v1/maintenance?enable=false). - Заархивировать отчёт и передать в систему учёта инцидентов (Jira, проект
XC-OPS).
- Отключить режим обслуживания (
Квалификационные требования к персоналу:
- Инженер по эксплуатации (категория не ниже 2-й),
- Допуск к консоли управления,
- Опыт работы с
kubectl,systemd,journalctl, - Знание принципов распределённых систем (кворум, репликация, шардирование).
3. Требования к техническим средствам
Программа xenon-diag может быть запущена на любом узле кластера XenonCache, где установлен агент xenon-agent >= 2.1.0. Минимальная конфигурация:
| Компонент | Требование | Обоснование |
|---|---|---|
| Операционная система | Ubuntu 22.04 LTS / Rocky Linux 9 / RHEL 9 | Поддержка systemd, cgroup v2 |
| Ядро Linux | ≥ 5.15 | Требуется io_uring и memfd_create |
| Процессор | x86_64 или arm64/v8, 2+ ядра | Параллельная проверка шардов |
| Оперативная память | 4 ГБ (при кластере ≤ 10 узлов) | Буферизация метаданных диагностики |
| Дисковое пространство | 1 ГБ свободно на /var | Логи, временные файлы, отчёты |
| Сетевые интерфейсы | lo, активный eth0, IPv4/IPv6 | Внутрикластерная коммуникация |
| Зависимости | bash ≥ 4.4, jq ≥ 1.6, curl ≥ 7.74, python3.10 | Обработка JSON, HTTP-клиент |
| Права | Пользователь xenon в группах adm, docker | Безопасный доступ к сокетам |
⚠ Примечание: Запуск от
rootзапрещён. Программа используетCAP_NET_ADMINиCAP_SYS_PTRACEчерезambient capabilities(см.systemdunit).
4. Описание функций
4.1. Максимальный состав технических средств, проверяемых программой
Программа xenon-diag поддерживает диагностику следующих компонентов:
| Компонент | Максимальная конфигурация | Примечание |
|---|---|---|
| Узлы XenonCache | до 64 узлов в одном кластере | Топология: mesh или star |
| Хранилища | mem://, ssd://, nvme://, ramdisk:// | Только локальные устройства |
| Сетевые интерфейсы | до 8 интерфейсов на узел | Включая VLAN, VRF |
| Внешние сервисы | consul, etcd, prometheus, loki | Только read-only проверки подключения |
| Оборудование | SMART-статус дисков, температура CPU (через ipmi-sensors) | При наличии ipmi и прав sudo diag-ipmi |
4.2. Совместное функционирование и обработка ошибок
Программа работает в два этапа:
-
Сбор метаданных
Выполняется параллельно по всем узлам через gRPC-канал кxenon-agent.
Запросы:/healthz(HTTP 200 OK),/metrics?name=alloc_bytes(Prometheus-формат),GET /v1/shards?state=all(состояние шардов).
-
Исполнение проверок
На каждом узле запускаются локальные скрипты (вchroot-окружении):- Проверка целостности индексов (
crc32хэш-свёртка), - Тест latency: 10 000
GET→SET→DEL(в памяти), - Проверка диска:
fio --name=diag --rw=randread --bs=4k --size=64M.
- Проверка целостности индексов (
Метод обработки ошибок:
| Тип ошибки | Обработка |
|---|---|
| Сетевая недоступность узла | Повтор 2 раза с backoff=2^i * 500ms. При 3 отказах — статус UNREACHABLE, исключить из диагностики, отправить alert. |
| Несовпадение контрольной суммы | Записать в отчёт checksum_mismatch: {shard_id, expected, actual}. Рекомендуется xenon-repair --shard <id>. |
Таймаут операции (> 30s) | Прервать поток, зафиксировать timeout_in_phase: <phase_name>, продолжить остальные проверки. |
Отказ оборудования (SMART Reallocated_Sector_Ct > 0) | Установить статус HW_DEGRADED, рекомендовать замену диска в ближайшие 72 ч. |
✅ Все ошибки логируются в структурированном формате JSON (см. 4.3).
4.3. Организация входных и выходных данных
Входные данные:
- CLI-аргументы:
xenon-diag \
--mode <quick|full> \
--nodes <node1,node2,...|all> \
--timeout <sec> \
--output <json|text|both> \
--log-level <error|warn|info|debug> - Переменные окружения (приоритет ниже CLI):
XENON_DIAG_MODE=full
XENON_DIAG_NODES=all
XENON_DIAG_OUTPUT_DIR=/var/log/xenon/diag
Выходные данные:
- Стандартный вывод (
stdout): краткий отчёт вtext(если--output=textилиboth). - Файл
<timestamp>.json: полный отчёт в формате:{
"version": "2.1.3",
"run_id": "diag-20251111T1420Z",
"cluster_id": "xc-prod-eu1",
"timestamp": "2025-11-11T14:20:03Z",
"mode": "full",
"summary": {
"nodes_total": 12,
"nodes_ok": 11,
"nodes_failed": 1,
"shards_checked": 96,
"shards_corrupted": 0,
"exit_code": 1
},
"nodes": [
{
"id": "node-07",
"status": "UNREACHABLE",
"error": "connection refused: 10.42.7.15:8080"
}
]
}
Коды возврата:
| Код | Значение | Действие |
|---|---|---|
0 | Все проверки пройдены | Штатная работа |
1 | Предупреждения (нестабильность, деградация) | Проверить логи, запланировать вмешательство |
2 | Критические ошибки (потеря данных, неработоспособность узла) | Немедленное вмешательство |
3 | Ошибки среды (недостаточно прав, отсутствуют зависимости) | Исправить окружение, повторить |
255 | Внутренняя ошибка программы | Обратиться к разработчикам, приложить лог --log-level=debug |
4.4. Взаимодействие устройств с программой и вывод результатов
- Программа не модифицирует состояние системы — только чтение и временные операции в памяти.
- Взаимодействие с оборудованием:
- Диски: через
libatasmartиsmartctl(толькоREAD DATA,SMART READ ATTRIBUTE), - Сеть: через
AF_PACKETсокеты (толькоrecvдля latency-проверок), - CPU: через
/proc/cpuinfo,/sys/class/thermal.
- Диски: через
- Результаты выводятся:
- В
stdout(если--output=text), - В файлы
*.jsonи*.log(автоматически, вXENON_DIAG_OUTPUT_DIR), - В
syslog(приоритетLOG_NOTICEдляexit_code=0,LOG_ERR— для≥2), - В Prometheus Pushgateway (если
PUSHGATEWAY_URLзадан): метрикаxenon_diag_last_run_status{mode="full"} = 0|1|2.
- В
📌 Пример вывода
stdout(--mode quick):[INFO] XenonDiag v2.1.3 starting (mode=quick, nodes=12)
[OK] node-01..node-06: latency < 2ms
[OK] node-07: skipped (maintenance mode)
[WARN] node-08: disk I/O latency 15ms (threshold=10ms)
[OK] All shards healthy (96/96)
[SUMMARY] exit_code=1 (warnings present)
5. Проверочный чек-лист по заполнению РТО
Используйте этот список до сдачи документа в версионирование. Каждый пункт — обязательное требование ГОСТ или критически важная практика.
✅ Структура и оформление
- Титульный лист содержит наименование, обозначение, дату, разработчика
- Аннотация присутствует (3–5 предложений), отражает назначение и аудиторию
- Содержание актуально и соответствует нумерации разделов
- Все разделы пронумерованы по ГОСТ 19.105-78 (1, 1.1, 1.2, …)
- Документ оформлен в соответствии с корпоративным стилем (шрифты, поля, колонтитулы)
✅ Содержание по требованиям ГОСТ 19.508-79
- Раздел «Введение» содержит назначение и перечень сопутствующих документов
- Раздел «Общие указания» описывает порядок, организацию и особенности проведения ТО
- Раздел «Требования к техническим средствам» указывает минимальный состав, обеспечивающий работу программы
- Раздел «Описание функций» включает:
- максимальный состав проверяемых технических средств
- описание совместного функционирования и метод обработки ошибок
- организацию входных и выходных данных
- взаимодействие устройств с программой и вывод результатов
✅ Техническая точность и безопасность
- Все версии ПО/ОС/зависимостей указаны точно, с ограничениями (
>=,<) - Приведены коды возврата с расшифровкой
- Есть хотя бы один рабочий пример запуска (CLI или HTTP)
- Указаны требования к квалификации персонала
- Присутствуют меры безопасности (права, режимы запуска, запреты)
- Все действия обратимы или идемпотентны (если применимо)
✅ Актуальность и поддержка
- В титуле/шапке указана актуальная версия системы, для которой документ применим
- Есть ссылка на процесс актуализации (например: «Обновляется при каждом minor-релизе»)
- Документ прошёл техническое ревью разработчиком и эксплуатацией
- Протестирован на стенде («сухой прогон» инструкций)
📎 Совет: интегрируйте этот чек-лист в CI/CD: при пуше в
docs/— запускайтеmarkdownlint,vale, и семантическую проверку по шаблону (например, черезjqна наличие ключевых полей в метаданных).